HowTo: Maximize GitHub Copilot’s Code Understanding of our repositories

news
code
copilot
development
Author

Dario Airoldi

Published

June 29, 2025

This document analyzes some strategies we are using to enhance GitHub Copilot’s understanding of our (Diginsight) codebases.

Proper techniques significantly improve Copilot’s code generation and answers to code-related questions.

Table of Contents

  1. Most Impactful Strategies
  2. Medium Impact
  3. Important but Less Direct Impact
  4. Best Practices Summary
  5. References

1. Most Impactful Strategies

These strategies have the most direct and immediate impact on GitHub Copilot’s ability to understand our code context and generate relevant suggestions.

1.1. Organize Workspace with Information for AI

What we can do: Structure our project files, documentation, and code comments in a way that maximizes Copilot’s ability to understand our project architecture, patterns, and domain knowledge.

Why this improves Copilot understanding: Workspace organization is the foundational strategy that encompasses all aspects of structuring our project for AI comprehension. This includes code comments, documentation placement, specialized AI-guidance files, and strategic organization that maximizes Copilot’s ability to understand our project’s context and domain knowledge.

Impact on suggestion relevance: Proper workspace organization has the highest impact because it provides the structural foundation for all other AI understanding techniques. When our workspace is organized for AI comprehension, Copilot can access and correlate information across multiple sources, leading to more contextually appropriate and architecturally sound suggestions.

1.1.1. Method Overview Comments

Provide domain context and decision-making rules to help Copilot understand our business logic:

// DOMAIN: This method handles period selection for data aggregation
// The aggregation range is determined based on the time period:
// - Today/Yesterday: Hourly aggregation
// - Week/Month: Daily aggregation
// - Semester/Year: Monthly aggregation
// The range directly affects data resolution and API performance
private (AggregationRange range, string format) ConfigurePeriodFormats(string periodType)
{
    // Implementation...
}

1.1.2. Strategic Code Comments

Focus on what Copilot cannot infer: While Copilot can generate standard XML documentation, it cannot understand our specific business rules, performance constraints, or domain-specific patterns. Focus comments on providing this unique context.

/// <summary>
/// Processes telemetry data batch with instrumentation and error handling
/// </summary>
/// <remarks>
/// BUSINESS RULE: Must maintain telemetry correlation across service boundaries
/// PERFORMANCE CONSTRAINT: Processing >1000 events/sec requires sampling (cost control)
/// DIGINSIGHT PATTERN: Always use ActivitySource for distributed tracing compliance
/// ANTI-PATTERN: Never log sensitive customer data in telemetry tags
/// </remarks>
public async Task<ProcessingResult> ProcessTelemetryDataAsync(TelemetryBatch batch)
{
    // BUSINESS LOGIC: Correlation ID required for cross-service tracing
    using var activity = _activitySource.StartActivity("ProcessTelemetryData");
    activity?.SetTag("batch.size", batch.Items.Count);
    
    try
    {
        // DOMAIN CONSTRAINT: Log structured data for observability dashboard
        _logger.LogInformation("Processing telemetry batch with {ItemCount} items", batch.Items.Count);
        
        var result = await _telemetryProcessor.ProcessAsync(batch);
        
        // COMPLIANCE: Success tracking required for SLA reporting
        activity?.SetTag("processing.success", true);
        return result;
    }
    catch (Exception ex)
    {
        // MONITORING: Error correlation essential for incident response
        activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
        _logger.LogError(ex, "Failed to process telemetry batch");
        throw;
    }
}

1.1.3. Directive Comments

Add explicit directives that guide Copilot’s code generation with prefixes like “COPILOT”:

// COPILOT: Standard Diginsight telemetry instrumentation pattern for service methods
// PATTERN: Activity creation with proper scoping and error handling
// DEPENDENCIES: Requires ActivitySource, ILogger<T>
// PERFORMANCE: Minimal overhead - activity creation is lightweight
public async Task<ProcessingResult> ProcessTelemetryDataAsync(TelemetryRequest request)
{
    // COPILOT: Always start with activity creation before any processing
    using var activity = _activitySource.StartActivity("ProcessTelemetryData");
    activity?.SetTag("request.type", request.Type);
    
    // Method implementation...
}

1.1.4. AI Context Files

Create documentation and context files across the repository that help AI understanding and choices:

Recommended Structure:

/MyProject/
├── .github/
│   └── copilot/
│       ├── prompts/                   # Team-shareable prompt templates
│       │   ├── telemetry-service.prompt       # Create telemetry services
│       │   ├── error-handling.prompt          # Add error handling patterns
│       │   ├── unit-tests.prompt             # Generate unit tests
│       │   └── performance-optimization.prompt
│       ├── knowledge/                 # Team-wide knowledge base
│       │   ├── team-conventions.md    # Shared coding standards
│       │   └── architecture-decisions.md
│       └── examples/                  # Reference implementations
│           ├── telemetry-patterns.cs
│           └── error-handling-examples.cs
├── .copilot/                          # Project-wide AI context
│   ├── architecture.md
│   ├── patterns.md
│   └── context/
│       ├── images/                    # Visual context for AI
│       └── examples/                  # Code examples and templates
├── src/
│   ├── docs/                          # Comprehensive documentation
│   │   ├── api-reference.md
│   │   └── domain-concepts.md
│   ├── Services/
│   │   ├── README.md                  # Services module overview
│   │   ├── Services.copilot.md        # AI guidance for Services module
│   │   ├── TelemetryService/
│   │   │   ├── README.md              # TelemetryService specific docs
│   │   │   ├── TelemetryService.copilot.md  # AI guidance for TelemetryService
│   │   │   ├── TelemetryService.cs
│   │   │   └── ITelemetryService.cs
│   │   └── LoggingService/
│   │       ├── README.md              # LoggingService specific docs
│   │       ├── LoggingService.copilot.md    # AI guidance for LoggingService
│   │       └── LoggingService.cs
│   └── Models/
│       ├── README.md                  # Data models overview
│       ├── Models.copilot.md          # AI guidance for data models
│       └── TelemetryModels.cs
└── README.md                          # Project root documentation

Types of Documentation Files to Distribute:

  1. Project Root README.md: High-level project overview, setup instructions, and quick Copilot prompts
  2. .github/copilot/ Folder: Team-shareable AI configuration following GitHub conventions, which can contain:
    • prompts/ subfolder: Reusable .prompt files that appear in Copilot’s Prompts panel
    • knowledge/ subfolder: Team-wide context documents explaining domain concepts and business rules
    • examples/ subfolder: Reference implementations and pattern templates
    • Team convention files: Shared coding standards, naming conventions, and AI instructions
  3. .copilot/ Folder: AI context files including:
    • Documentation: Architecture decisions, coding patterns, and troubleshooting guides
    • Code Examples: Reference implementations and pattern templates
    • Configuration Files: AI-specific settings and behavior guidelines
    • Visual Context: Diagrams, images, and flowcharts that explain complex concepts
    • Data Files: Sample data, schemas, and API responses for context
  4. src/docs/ Folder: Comprehensive API references, domain concepts, and technical specifications
  5. Module-Level README.md: Overview of each major code module (Services/, Models/, etc.)
  6. Component-Level README.md: Specific documentation for individual services or components
  7. .copilot.md Files: Specialized AI guidance files next to major components (e.g., TelemetryService.copilot.md)

1.1.5. Repository-Level Documents

GitHub Copilot leverages two root directories for AI-enhanced development, each serving distinct but complementary purposes:

.github/copilot/ Directory

This directory follows GitHub’s official conventions for team-shareable Copilot configuration and can contain:

  • Prompt Files (prompts/ subfolder): Reusable .prompt files that appear directly in Copilot’s Prompts panel for all team members
  • Knowledge Bases (knowledge/ subfolder): Team-wide context documents (.md files) explaining domain concepts, architecture decisions, and business rules
  • Code Examples (examples/ subfolder): Reference implementations and pattern templates that demonstrate team coding standards
  • Team Conventions (.md files): Shared coding standards, naming conventions, and development practices
  • AI Instructions (.md files): Team-specific guidelines for how AI should assist with your codebase
.copilot/ Directory

This directory serves as a local developer context repository containing project-specific reference materials:

  • Architecture Documentation: System design documents, component relationships, and technical specifications
  • Troubleshooting Guides: Common issues, debugging approaches, and solution patterns
  • Domain Context: Business logic explanations, workflow descriptions, and project-specific terminology
  • Code Examples: Project-specific implementation patterns and usage examples
  • Images and Diagrams: Visual documentation that helps explain complex concepts
Aspect .github/copilot/ .copilot/
Purpose Team-shareable AI configuration following GitHub conventions Local developer context and project-specific reference materials
Visibility Prompt files appear in Copilot UI; other contents provide team-wide background knowledge All contents provide background knowledge but don’t appear directly in the Copilot UI
Scope Team-wide standards, shared workflows, and common development tasks Project-specific context, architecture details, and local development guidance

Key Benefits:

  • Layered Context: Copilot accesses the most relevant documentation based on where we’re working
  • Easy Maintenance: Documentation stays close to the code it describes
  • Focused Information: Each file addresses specific concerns without overwhelming detail

1.1.6. Component-Specific Documentation

Create targeted context files with the .copilot.md extension that provide domain-specific knowledge for individual components:

# Diginsight.Telemetry.copilot.md

DATABASE: diginsightdb (CosmosDB)
COLLECTIONS:
- data (projects, entities)
- data-sources (source types)

KEY CONCEPTS:
- Project ID 12345678-0c85-4592-8396-3f3e8656ed03 = "Diginsight Sample Project"
- Data Types: Activity Events, Telemetry, Configuration
- Period aggregation affects data granularity and API performance

ANTI-PATTERNS:
- Avoid dynamic activity names (high cardinality)
- Don't use generic logger categories
- Never log sensitive data in telemetry

1.1.7. Architecture Documentation

Create comprehensive architecture documentation that provides system-level context:

# .copilot/architecture.md - Diginsight Telemetry System Architecture

## System Overview
Diginsight Telemetry is a distributed observability platform built on OpenTelemetry standards.

## Core Components
- **Activity Sources**: Distributed tracing entry points
- **Telemetry Processors**: Data transformation and enrichment
- **Export Pipeline**: Batching and transmission to observability backends
- **Configuration System**: Dynamic settings and sampling controls

## Component Interactions
```text
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Application     │───▶│ ActivitySource  │───▶│ Telemetry       │
│ Code            │    │ (Instrumentation)│    │ Processor       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                                                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Azure Monitor / │◀───│ Export Pipeline │◀───│ Batch Processor │
│ Other Backends  │    │ (OTLP)          │    │ (Sampling)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Key Architectural Decisions

  • OpenTelemetry Standard: Vendor-neutral observability
  • Push-based Collection: Better performance than pull-based
  • Structured Logging: Correlation with distributed traces
  • Sampling Strategy: Cost control while maintaining visibility

1.1.8. Documentation Header Hierarchy

Use consistent header hierarchies to establish clear information structure:

# Diginsight Telemetry System
## Core Components
### Data Retrieval Flow
#### ProcessTelemetryDataAsync Method

This hierarchical structure helps Copilot understand the relationship between concepts and suggest code that follows the same organizational patterns.

1.1.9. README Integration Strategy

Create AI-friendly project documentation in our README files:

# Diginsight Telemetry - AI Development Guide

## For GitHub Copilot Users

This project uses OpenTelemetry for distributed tracing. Common patterns:

1. **Activity Creation**: Always use `_activitySource.StartActivity()`
2. **Error Handling**: Set activity status on exceptions
3. **Tagging**: Use semantic tag names following OpenTelemetry conventions
4. **Logging**: Correlate logs with activities using structured logging

## Quick Copilot Queries

- "Generate a new telemetry service following Diginsight patterns"
- "Add error handling to this method using our standard approach"
- "Create unit tests for telemetry methods with proper mocking"

1.1.10. External References Strategy

Important Limitation: Copilot cannot access external URLs, wikis, or online documentation during code generation. However, we can still reference them strategically:

# .copilot/architecture.md

## External Documentation References

### OpenTelemetry Standards
- **Specification**: https://opentelemetry.io/docs/specs/otel/
- **Key Patterns**: Trace context propagation, semantic conventions
- **Local Summary**: Always use W3C trace context headers for correlation

### Azure DevOps Wiki References  
- **Team Architecture Decisions**: https://dev.azure.com/ourorg/project/_wiki/wikis/Architecture
- **Key Decisions**: Service mesh adoption, database partitioning strategy
- **Local Summary**: Use event-driven patterns for telemetry aggregation

### Internal API Documentation
- **REST API Docs**: https://internal-docs.company.com/telemetry-api
- **Key Endpoints**: /api/telemetry/batch, /api/metrics/query
- **Local Summary**: Use batch endpoints for >100 events, single for real-time

Best Practice for External References:

  1. Include the link for human developers
  2. Summarize key information locally that Copilot can understand
  3. Extract essential patterns into our local documentation
  4. Copy critical code examples rather than linking to them

1.2. Semantic Naming for AI Understanding

What we can do: Use descriptive, hierarchical naming conventions for methods, classes, and variables that clearly convey intent and relationships within our codebase.

Why this improves Copilot understanding: Descriptive, hierarchical naming conventions help Copilot understand the intent and relationships within our codebase. When method names, class names, and variable names follow consistent patterns that convey meaning, Copilot can better predict what related code should look like and suggest appropriate completions.

Impact on suggestion relevance: Semantic naming enables Copilot to suggest code that follows our established patterns, maintains consistency across our codebase, and uses meaningful names that align with our domain terminology.

Use Descriptive, Hierarchical Naming

// GOOD: Clear intent and hierarchy
public class DiginsightTelemetryDataAggregationService
{
    public async Task<PeriodAggregatedData> GetHourlyAggregatedTelemetryData(...)
    public async Task<PeriodAggregatedData> GetDailyAggregatedTelemetryData(...)
}

// COPILOT understands this pattern and suggests similar methods
public class DiginsightLogAnalysisService  
{
    // Copilot will suggest: GetHourlyAggregatedLogData, GetDailyAggregatedLogData
}

Pattern-Based Method Names

// This comment helps Copilot understand the expected pattern
public async Task<ApiResponse<TelemetryMetrics>> GetHourlyTelemetryMetricsAsync(...)
// Copilot will now suggest GetDailyTelemetryMetricsAsync, GetWeeklyTelemetryMetricsAsync

// Domain context in variable names guides suggestions
var hourlyDataRetrieval = new TelemetryDataRetrieval();
// Copilot understands: dailyDataRetrieval, weeklyDataRetrieval should follow

1.3. Domain Concept Documentation

What we can do: Clearly define and document our domain-specific terminology, business concepts, and their relationships to help Copilot understand our business logic.

Why this improves Copilot understanding: Domain-specific terminology and concepts are crucial for Copilot to understand our business logic. When we clearly define terms like “Data Sources,” “Groups,” and “Activity Events,” Copilot can better understand the context of our code and suggest domain-appropriate solutions rather than generic programming patterns.

Impact on suggestion relevance: With clear domain concepts, Copilot can suggest variable names, method signatures, and logic flows that align with our business domain, making suggestions more meaningful and reducing the need for manual corrections.

Core Domain Concepts

# Domain Concepts

## Data Sources
Types of data being processed (Telemetry, Logs, etc.). Each source has its own metrics.

## Groups
Collections of entities with data measurements. Can be:
- Runtime Group: System-defined grouping
- Custom Group: User-defined collection of entities

## Data Types
Measurements tracked for each source:
- Activity Events: Application activity logs
- Telemetry: Performance and usage data
- Configuration: Dynamic settings

Example Usages

## Common Usage Patterns

### Period Selection

// Period selection affects the data aggregation range
switch (settings.Period)
{
    case "Today":
        // Uses hourly aggregation (24 data points)
        range = Diginsight.Common.Querying.AggregationRange.Hour;
        break;
    case "CurrentMonth":
        // Uses daily aggregation (28-31 data points)
        range = Diginsight.Common.Querying.AggregationRange.Day;
        break;
}

1.4. Code Patterns and Conventions

What we can do: Establish and document consistent code patterns, naming conventions, error handling approaches, and architectural patterns that should be applied throughout our codebase.

Why this improves Copilot understanding: Establishing and documenting code patterns and conventions helps Copilot understand our team’s preferred approaches to common programming tasks. This includes naming conventions, error handling patterns, logging strategies, and architectural patterns that should be consistently applied.

Impact on suggestion relevance: Clear code patterns and conventions ensure that Copilot’s suggestions follow our established standards, maintain consistency across the codebase, and adhere to our team’s best practices, resulting in code that fits seamlessly into our existing project structure.

Naming Conventions

# Coding Standards

## Activity Names
- Use hierarchical names: `Diginsight.Service.Method`
- Include operation type: `Diginsight.Data.Query`, `Diginsight.Http.Request`
- Avoid dynamic names that create high cardinality

## Logger Categories
- Use class-based categories: `ILogger<MyService>`
- For static contexts: `ILogger<Program>` or specific category names
- Avoid generic categories like "Application" or "System"

## Metric Names
- Use dot notation: `diginsight.request.duration`
- Include units: `diginsight.memory.bytes`, `diginsight.duration.milliseconds`
- Follow OpenTelemetry semantic conventions

Common Patterns

// Standard method instrumentation pattern
public async Task<Result> ProcessAsync(Request request)
{
    using var activity = _activitySource.StartActivity();
    activity?.SetTag("request.id", request.Id);
    
    try
    {
        _logger.LogInformation("Processing request {RequestId}", request.Id);
        
        var result = await DoWorkAsync(request);
        
        activity?.SetTag("result.status", "success");
        return result;
    }
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
        _logger.LogError(ex, "Failed to process request {RequestId}", request.Id);
        throw;
    }
}

1.5. Effective Prompting Strategies

What we can do: Develop and document standardized prompting patterns that help developers leverage the documentation in our codebase when working with Copilot.

Why this improves Copilot understanding: While other strategies focus on making our codebase more understandable to Copilot, effective prompting strategies create a crucial feedback loop between our documentation and AI interaction. When developers know how to reference existing patterns, naming conventions, and architectural decisions in their prompts, Copilot can locate and apply this contextual information more effectively.

Impact on suggestion relevance: Strategic prompting dramatically improves Copilot’s ability to generate code that aligns with our established patterns and architectural constraints. By teaching developers how to prompt effectively, we create a multiplier effect that enhances the value of all our other documentation efforts.

Reference-Based Prompts

Train the team to reference specific documentation in prompts:

// Example prompt: "Create a telemetry method following the patterns in Diginsight.Core.copilot.md"
// Example prompt: "Add error handling similar to ProcessTelemetryDataAsync"

Pattern-Driven Prompts

Create a “prompt dictionary” that developers can reference:

# Effective Copilot Prompts

## For Telemetry Instrumentation
- "Create a method that processes [data type] with standard Diginsight telemetry instrumentation"
- "Add proper activity tracking to this method following our distributed tracing pattern"

## For Error Handling
- "Implement our standard error handling pattern with proper activity status in this method"
- "Update this method to include structured logging with our telemetry correlation pattern"

Component-Specific Prompts

Document component-specific prompting patterns:

# Telemetry Service Prompts

When working with telemetry services, use these specific prompts:

- "Create a new telemetry processor that handles [data type] following our sampling pattern"
- "Implement a batch processing method for telemetry data that follows our performance guidelines"
- "Generate unit tests for this telemetry method with proper activity source mocking"

1.6. Code Annotations for AI Tools

What we can do: Implement a consistent annotation system specifically designed to guide AI tools like Copilot, using distinct markers that highlight patterns, constraints, and relationships.

Why this improves Copilot understanding: Standard comments are helpful, but specialized AI annotations create a targeted communication channel with Copilot. These annotations stand out from regular comments and provide structured guidance that Copilot can more easily identify and follow when generating suggestions.

Impact on suggestion relevance: AI-specific annotations dramatically improve Copilot’s ability to understand our code’s unique constraints, patterns, and relationships. They serve as clear signposts that help Copilot navigate our codebase and generate suggestions that align perfectly with our team’s expectations.

AI Directive Annotations

Create standardized AI directive annotations:

// @ai:pattern - This class follows the Repository pattern with CosmosDB integration
// @ai:constraint - This method must maintain correlation IDs across service boundaries
// @ai:relationship - This service depends on IDataSourceRepository and IEntityAdapter
public class DiginsightService
{
    // @ai:example - Standard constructor injection pattern
    public DiginsightService(IDataSourceRepository repo, IEntityAdapter adapter)
    {
        // Implementation...
    }

    // @ai:pattern - Standard telemetry method with proper instrumentation
    // @ai:performance - Batch operations for >100 items to reduce API calls
    public async Task<Result> ProcessDataAsync(Request request)
    {
        // Implementation...
    }
}

Schema Annotations

Add structured schema annotations to complex data models:

// @ai:schema - ProjectEntity schema
// @ai:property id - GUID format, globally unique identifier
// @ai:property name - User-visible project name, max 100 chars
// @ai:property type - Must be "project", used for CosmosDB querying
public class ProjectEntity
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public string Type { get; } = "project";
}

Relationship Annotations

Document component relationships with special annotations:

// @ai:depends-on - ILogger<T>, ActivitySource
// @ai:consumed-by - TelemetryService, MetricsService
// @ai:implements - OpenTelemetry.ActivitySource pattern
public class DiginsightActivitySource
{
    // Implementation...
}

2. Medium Impact

These strategies provide substantial improvements to Copilot’s understanding, particularly for code structure, patterns, and domain-specific implementations.

2.1. AI-Optimized Code Comments

What we can do: Structure our code comments specifically to provide AI with tactical context about implementation details, dependencies, and performance considerations.

Why this improves Copilot understanding: Strategic code comments provide tactical context that helps Copilot understand specific implementation details, dependencies, and performance considerations. While less impactful than architecture documentation, they provide valuable hints for method-level code generation.

Impact on suggestion relevance: AI-optimized comments help Copilot suggest code that follows our specific patterns and handles edge cases appropriately, though they primarily influence local code suggestions rather than system-wide architectural decisions.

Structured Comments for AI

Structure comments specifically for AI understanding:

// COPILOT: Standard Diginsight telemetry instrumentation pattern for service methods
// PATTERN: Activity creation with proper scoping and error handling
// DEPENDENCIES: Requires ActivitySource, ILogger<T>
// PERFORMANCE: Minimal overhead - activity creation is lightweight
public async Task<ProcessingResult> ProcessTelemetryDataAsync(TelemetryRequest request)
{
    // COPILOT: Standard Diginsight activity creation pattern
    using var activity = _activitySource.StartActivity("ProcessTelemetryData");
    activity?.SetTag("request.type", request.Type);
    
    try
    {
        _logger.LogInformation("Processing telemetry request {RequestId}", request.Id);
        var result = await _telemetryProcessor.ProcessAsync(request);
        activity?.SetTag("result.status", "success");
        return result;
    }
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
        _logger.LogError(ex, "Failed to process telemetry request {RequestId}", request.Id);
        throw;
    }
}

2.2. Implementation Examples

What we can do: Provide concrete implementation examples that demonstrate our preferred patterns and coding styles, serving as templates for Copilot to follow.

Why this improves Copilot understanding: Concrete implementation examples show Copilot the preferred patterns and coding styles for our project. When Copilot sees how we handle period calculations or batch processing, it can suggest similar patterns for new functionality, maintaining consistency across our codebase.

Impact on suggestion relevance: Implementation examples serve as templates for Copilot to follow, ensuring that new code suggestions match our existing patterns, naming conventions, and architectural approaches, leading to more cohesive and maintainable code.

Period Helper Methods

Extract common period calculation code:

/// <summary>
/// Configures period formats and ranges based on the period type
/// </summary>
/// <param name="periodType">The selected period (Today, Yesterday, CurrentWeek, etc.)</param>
/// <param name="projectLocalNow">The current time in the project's local timezone</param>
/// <returns>Configuration for the selected period</returns>
private (Diginsight.Common.Querying.AggregationRange Range, string Format, string TitleFormat) 
    ConfigurePeriod(string periodType, DateTime projectLocalNow)
{
    switch (periodType)
    {
        case "Today":
        case "Yesterday":
            return (Diginsight.Common.Querying.AggregationRange.Hour, "HH:mm", "dd MMM yyyy - HH:mm");
        // Additional cases...
    }
}

Data Source Batch Processing

/// <summary>
/// Retrieves and processes all data sources for a project in a single batch operation
/// </summary>
/// <param name="projectId">The project ID</param>
/// <param name="group">The entity group to analyze</param>
/// <param name="dateRange">Date range for data retrieval</param>
/// <returns>Dictionary mapping source types to their data</returns>
private async Task<Dictionary<string, GroupAggregation<AggregateValues>>> 
    GetBatchData(Guid projectId, DiginsightClasses.IGroup group, DateRange dateRange)
{
    // Implementation that reduces API calls through batching
}

2.3. Data Model Documentation

What we can do: Document our data structures, relationships, and database schema to help Copilot understand how data flows through our application.

Why this improves Copilot understanding: Data models are the foundation of any application. When Copilot understands our data structures, relationships, and database schema, it can suggest appropriate CRUD operations, data transformations, and validation logic. This is especially critical for telemetry systems where data flows through multiple transformation stages.

Impact on suggestion relevance: With clear data model documentation, Copilot can suggest proper entity mappings, database queries, and data processing patterns that respect our schema constraints and business rules, reducing bugs and improving code quality.

Key Data Models

# Core Data Models

## DiginsightData
Primary response model with hierarchical structure:

- DiginsightData
  - DataQuality (validity warnings)
  - Detail
    - Chart[] (time series data)
    - DataGroup (aggregated values)
  - PeriodDate (date ranges)

Database Structure

# Database Structure

## Azure Cosmos DB (diginsightdb)
- **Collection: data**
  - Projects (key: id)
    - Example: "id": "12345678-0c85-4592-8396-3f3e8656ed03", "name": "Diginsight Sample Project"
  - Entities (partitioned by projectId)
  - Groups (custom entity groups)

## Sample Documents
```json
{
  "id": "12345678-0c85-4592-8396-3f3e8656ed03",
  "name": "Diginsight Sample Project",
  "type": "project",
  "_etag": "\"00000000-0000-0000-0000-000000000000\""
}

2.4. API and Interface Documentation

What we can do: Document our API contracts, method signatures, and interface boundaries to help Copilot understand system contracts and expected behaviors.

Why this improves Copilot understanding: Clear API and interface documentation helps Copilot understand the contracts and boundaries within our system. When Copilot knows the signatures, parameters, and expected behavior of our public APIs, it can suggest proper implementations and usage patterns.

Impact on suggestion relevance: API documentation enables Copilot to suggest code that correctly implements interfaces, respects method signatures, and follows our established patterns for API design and usage, reducing integration errors and improving code consistency.

2.5. Code Relationship Documentation

What we can do: Document how different classes, services, and components interact with each other, including dependency flows and architectural patterns.

Why this improves Copilot understanding: Understanding how different classes, services, and components interact is crucial for Copilot to suggest appropriate design patterns and architectural solutions. When Copilot knows that DiginsightService depends on IDataSourceRepository, it can suggest proper dependency injection patterns and interface implementations.

Impact on suggestion relevance: Clear relationship documentation enables Copilot to suggest code that respects our architecture, follows dependency flow patterns, and maintains proper separation of concerns, leading to more maintainable and consistent code suggestions.

Class Dependencies

# Component Relationships

## Service Layer
- DiginsightService 
  → IDataSourceRepository (CosmosDB data access)
  → IEntityAdapter (entity access)
  → IGroupAdapter (group management)

## Data Flow
1. Widget request → ProcessTelemetryDataAsync
2. Period calculation and group resolution
3. For each data source type:
   - Filter entities by data source
   - Fetch data
   - Process into chart format

Visual Documentation

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Data Sources    │────▶│ Entity Group    │────▶│ Data            │
│ (Telemetry,     │     │ (Custom or      │     │ (Activity,      │
│  Logs, etc.)    │     │  Runtime)       │     │  Telemetry)     │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Performance Considerations

What we can do: Document performance constraints, bottlenecks, and optimization strategies that are specific to our application domain.

Why this improves Copilot understanding: Performance constraints and optimization strategies are critical context for code generation. When Copilot understands that ProcessTelemetryDataAsync has performance considerations for batch processing, it can suggest optimizations like parallel processing, sampling, or async patterns that address these specific telemetry concerns.

Impact on suggestion relevance: Performance documentation helps Copilot suggest code that considers scalability, efficiency, and resource usage from the start, preventing performance issues rather than requiring later optimization.

# Performance Considerations

## Current Bottlenecks
- ProcessTelemetryDataAsync processes telemetry batches with proper instrumentation
- Current load: ~20 calls/sec in production
- Each data source creates a new filtered group object

## Optimization Strategies
- Batch data source calls where possible
- Cache filtered groups for reuse
- Implement more efficient filtering to reduce API calls

3. Important but Less Direct Impact

These strategies provide foundational improvements that support overall code comprehension and long-term maintainability, though their impact on immediate code suggestions may be less direct.

3.1. Configuration and Environment Documentation

What we can do: Document our configuration structures, environment variables, and dependency injection patterns to help Copilot understand how our application behaves in different environments.

Why this improves Copilot understanding: Configuration is critical for understanding how an application behaves in different environments. When Copilot understands our configuration structure, environment variables, and dependency injection patterns, it can suggest code that properly handles configuration changes and environment-specific behavior.

Impact on suggestion relevance: Configuration documentation enables Copilot to suggest code that properly accesses configuration values, handles environment differences, and follows our established patterns for dependency injection and service registration.

Configuration Files Documentation

Document configuration patterns and environment-specific settings:

```markdown
# Configuration Management

## appsettings.json Structure
```json
{
  "Diginsight": {
    "Telemetry": {
      "DefaultLogLevel": "Information",
      "EnableDynamicLogging": true,
      "SamplingRate": 0.1
    },
    "OpenTelemetry": {
      "ServiceName": "Diginsight.Sample",
      "ServiceVersion": "1.0.0"
    }
  }
}

Environment Variables

  • DIGINSIGHT_LOG_LEVEL: Override default log level
  • DIGINSIGHT_SAMPLING_RATE: Control telemetry sampling
  • AZURE_CONNECTION_STRING: Azure Monitor connection

Dependency Injection Patterns

// Standard DI registration pattern for Diginsight Telemetry
services.AddDiginsightTelemetry(options =>
{
    options.ServiceName = "MyService";
    options.EnableConsoleLogging = true;
    options.EnableAzureMonitor = !isDevelopment;
});

3.2. Testing Strategy and Error Patterns

What we can do: Document common error scenarios, testing patterns, and expected behaviors to help Copilot suggest robust code that handles edge cases appropriately.

Why this improves Copilot understanding: Testing documentation and error patterns help Copilot understand expected behavior and common failure scenarios. This knowledge is crucial for suggesting robust code that handles edge cases and follows established testing patterns in our project.

Impact on suggestion relevance: With clear testing strategies and error patterns, Copilot can suggest code that includes appropriate error handling, follows our testing conventions, and anticipates common problems, leading to more reliable and testable code suggestions.

Common Error Scenarios

Document typical error patterns and their solutions:

# Common Error Patterns

## Configuration Errors
- Missing connection strings → Check appsettings.json
- Invalid service names → Verify OpenTelemetry configuration
- Permission issues → Check Azure RBAC settings

## Performance Issues
- High memory usage → Check sampling rates
- Slow telemetry → Review batch export settings
- Missing traces → Verify instrumentation setup

## Testing Patterns
- Use TestHost for integration tests
- Mock ILogger<T> for unit tests
- Use InMemoryExporter for telemetry validation

Test Examples

[Test]
public async Task Should_Generate_Telemetry_For_Method_Execution()
{
    // Arrange
    using var activity = ActivitySource.StartActivity("test-operation");
    
    // Act
    var result = await _service.ProcessDataAsync();
    
    // Assert
    Assert.IsNotNull(activity);
    Assert.AreEqual("test-operation", activity.DisplayName);
}

API and Interface Documentation

What we can do: Document public API contracts, method signatures, and interface behaviors to ensure Copilot suggests code that correctly implements our system’s contracts.

Why this improves Copilot understanding: Clear API and interface documentation helps Copilot understand the contracts and boundaries within our system. When Copilot knows the signatures, parameters, and expected behavior of our public APIs, it can suggest proper implementations and usage patterns.

Impact on suggestion relevance: API documentation enables Copilot to suggest code that correctly implements interfaces, respects method signatures, and follows our established patterns for API design and usage, reducing integration errors and improving code consistency.

Public API Contracts

# Public APIs

## IDiginsightTelemetryService
Primary interface for telemetry operations:

```csharp
public interface IDiginsightTelemetryService
{
    /// <summary>
    /// Starts a new activity with automatic telemetry collection
    /// </summary>
    /// <param name="activityName">Name of the activity</param>
    /// <param name="tags">Optional tags for the activity</param>
    /// <returns>Disposable activity that ends when disposed</returns>
    IDisposable StartActivity(string activityName, Dictionary<string, object>? tags = null);
    
    /// <summary>
    /// Logs structured data with telemetry correlation
    /// </summary>
    void LogStructured<T>(LogLevel level, string message, T data);
}

Extension Methods

// Common extension patterns for telemetry
public static class TelemetryExtensions
{
    public static IServiceCollection AddDiginsightTelemetry(
        this IServiceCollection services, 
        Action<DiginsightOptions> configure)
    {
        // Configuration logic
    }
}

3.3. Architecture Decision Records

What we can do: Create Architecture Decision Records (ADRs) that document why certain technical choices were made, providing historical context for architectural decisions.

Why this improves Copilot understanding: Architecture Decision Records (ADRs) provide context about why certain technical choices were made. This historical context helps Copilot understand not just what patterns to follow, but why they were chosen, enabling it to suggest solutions that align with our architectural philosophy and constraints.

Impact on suggestion relevance: ADRs help Copilot understand the reasoning behind architectural decisions, enabling it to suggest code that respects existing design choices, avoids previously rejected approaches, and aligns with our team’s architectural principles and trade-offs.

ADR Template

# ADR-001: Use OpenTelemetry for Distributed Tracing

## Status
Accepted

## Context
Need standardized observability across microservices with vendor-neutral approach.

## Decision
Adopt OpenTelemetry as the primary telemetry framework for Diginsight.

## Consequences
- **Positive**: Vendor-neutral, industry standard, rich ecosystem
- **Negative**: Learning curve, additional complexity in configuration
- **Neutral**: Migration effort from existing logging frameworks

## Implementation Notes
- Use OTLP exporters for data transmission
- Implement custom samplers for cost control
- Maintain backward compatibility with existing ILogger patterns

Key Decisions

Document major architectural choices:

# Architecture Decisions

## Telemetry Collection Strategy
- **Decision**: Use push-based telemetry with batching
- **Rationale**: Better performance, reduced network overhead
- **Trade-offs**: Slight delay in telemetry visibility

## Configuration Management
- **Decision**: Use strongly-typed configuration classes
- **Rationale**: Compile-time safety, better IntelliSense support
- **Implementation**: `IOptions<T>` pattern with validation

4. Best Practices Summary

  1. Consistent Structure: Use clear, hierarchical document organization
  2. Domain Concepts: Define all business-specific terms and relationships
  3. Database Details: Document database structure, collections, and example records
  4. Component Relationships: Show how classes and methods interconnect
  5. Performance Notes: Document current metrics and optimization opportunities
  6. Strategic Comments: Add context-rich comments at key decision points
  7. Dedicated Copilot Files: Create .copilot.md files for AI-specific documentation
  8. Visual Representations: Include diagrams where relationships are complex
  9. Implementation Examples: Show ideal code patterns and optimizations
  10. Configuration Documentation: Document all configuration files, environment variables, and setup patterns
  11. Error Pattern Documentation: Catalog common errors, their causes, and solutions
  12. Testing Strategy: Document test patterns, mocking strategies, and validation approaches
  13. API Contracts: Clearly document public interfaces, parameters, and return types
  14. Architecture Decisions: Record why technical choices were made using ADRs
  15. Code Conventions: Establish and document naming conventions, patterns, and standards
  16. Reference Documentation: Explicitly reference documentation in Copilot queries
  17. Source vs. Generated Documentation: Place AI-readable markdown in source directories (src/docs/) rather than generated output directories (docs/) - Copilot reads markdown files, not HTML

5. References

  • Getting Code Suggestions in Your IDE with GitHub Copilot

    Official GitHub documentation covering how Copilot understands code context and generates suggestions. Includes specific guidance on improving code suggestions through comments, documentation, and code structure - directly applicable to telemetry system documentation strategies.

  • Advanced GitHub Copilot: Domain-Specific Knowledge Transfer

    Research on how Copilot learns domain-specific patterns and technical vocabularies. Includes case studies showing how specialized documentation improves Copilot’s understanding of monitoring and telemetry systems.

  • OpenTelemetry Semantic Conventions

    Comprehensive guide to documenting observability concepts, metrics, and telemetry flows using industry-standard semantic conventions. Essential for creating consistent, AI-understandable documentation in telemetry systems. Covers naming conventions, attribute definitions, and documentation patterns that help AI tools understand telemetry domain concepts.

  • .NET Observability with OpenTelemetry

    Microsoft’s official guide to implementing observability in .NET applications using OpenTelemetry. Demonstrates how to structure telemetry code, configuration, and documentation patterns that align with both human understanding and AI code comprehension in .NET telemetry systems.

  • ChatGPT versus Traditional Question Answering for Knowledge Graphs

    Academic research comparing conversational AI systems with traditional knowledge extraction systems. Provides insights into how AI tools like Copilot process and understand domain-specific knowledge structures, particularly relevant for complex technical domains like distributed tracing and observability systems.

  • Configuring GitHub Copilot in Your Environment

    Technical guide covering how to structure code comments and documentation to maximize AI comprehension of complex technical domains. Particularly valuable for telemetry systems with complex data flows and relationships.

By implementing these specialized documentation practices, our team can significantly enhance Copilot’s understanding of the Diginsight Telemetry system, leading to more accurate code suggestions that respect our domain-specific patterns and requirements.